<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.4"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Flow-IPC: ipc::shm::classic::Pool_arena Class Reference</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr id="projectrow">
  <td id="projectalign">
   <div id="projectname">Flow-IPC<span id="projectnumber">&#160;1.0.2</span>
   </div>
   <div id="projectbrief">Flow-IPC project: Public API.</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.4 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search",'Search','.html');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
/* @license-end */
</script>
<div id="main-nav"></div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div id="nav-path" class="navpath">
  <ul>
<li class="navelem"><a class="el" href="namespaceipc.html">ipc</a></li><li class="navelem"><a class="el" href="namespaceipc_1_1shm.html">shm</a></li><li class="navelem"><a class="el" href="namespaceipc_1_1shm_1_1classic.html">classic</a></li><li class="navelem"><a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html">Pool_arena</a></li>  </ul>
</div>
</div><!-- top -->
<div class="header">
  <div class="summary">
<a href="#pub-types">Public Types</a> &#124;
<a href="#pub-methods">Public Member Functions</a> &#124;
<a href="#pub-static-methods">Static Public Member Functions</a> &#124;
<a href="#pub-attribs">Public Attributes</a> &#124;
<a href="#related">Related Functions</a> &#124;
<a href="classipc_1_1shm_1_1classic_1_1Pool__arena-members.html">List of all members</a>  </div>
  <div class="headertitle"><div class="title">ipc::shm::classic::Pool_arena Class Reference</div></div>
</div><!--header-->
<div class="contents">

<p>A SHM-classic interface around a single SHM pool with allocation-algorithm services by boost.interprocess, as in <code>bipc::managed_shared_memory</code>, with symmetric read/write semantics, compatible with <a class="el" href="namespaceipc_1_1shm_1_1stl.html" title="ipc::shm sub-module providing integration between STL-compliant components (including containers) and...">ipc::shm::stl</a> STL-compliance and SHM-handle borrowing manually or via <a class="el" href="namespaceipc_1_1session.html" title="Flow-IPC module providing the broad lifecycle and shared-resource organization – via the session conc...">ipc::session</a>.  
 <a href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#details">More...</a></p>

<p><code>#include &lt;pool_arena.hpp&gt;</code></p>

<p>Inherits flow::log::Log_context, and boost::noncopyable.</p>
<div class="dynheader">
Collaboration diagram for ipc::shm::classic::Pool_arena:</div>
<div class="dyncontent">
<div class="center"><iframe scrolling="no" frameborder="0" src="classipc_1_1shm_1_1classic_1_1Pool__arena__coll__graph.svg" width="284" height="203"><p><b>This browser is not able to show SVG: try Firefox, Chrome, Safari, or Opera instead.</b></p></iframe>
</div>
<center><span class="legend">[<a href="graph_legend.html">legend</a>]</span></center></div>
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="pub-types" name="pub-types"></a>
Public Types</h2></td></tr>
<tr class="memitem:a07fec7ff0ba494dca0f0a010270cc35f"><td class="memTemplParams" colspan="2">template&lt;typename T &gt; </td></tr>
<tr class="memitem:a07fec7ff0ba494dca0f0a010270cc35f"><td class="memTemplItemLeft" align="right" valign="top">using&#160;</td><td class="memTemplItemRight" valign="bottom"><a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a07fec7ff0ba494dca0f0a010270cc35f">Pointer</a> = ::ipc::bipc::offset_ptr&lt; T &gt;</td></tr>
<tr class="memdesc:a07fec7ff0ba494dca0f0a010270cc35f"><td class="mdescLeft">&#160;</td><td class="mdescRight">SHM-storable fancy-pointer.  <a href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a07fec7ff0ba494dca0f0a010270cc35f">More...</a><br /></td></tr>
<tr class="separator:a07fec7ff0ba494dca0f0a010270cc35f"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a662a55c9ba6eb5c389ddf9780ee801cb"><td class="memTemplParams" colspan="2">template&lt;typename T &gt; </td></tr>
<tr class="memitem:a662a55c9ba6eb5c389ddf9780ee801cb"><td class="memTemplItemLeft" align="right" valign="top">using&#160;</td><td class="memTemplItemRight" valign="bottom"><a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a662a55c9ba6eb5c389ddf9780ee801cb">Handle</a> = boost::shared_ptr&lt; T &gt;</td></tr>
<tr class="memdesc:a662a55c9ba6eb5c389ddf9780ee801cb"><td class="mdescLeft">&#160;</td><td class="mdescRight">Outer handle to a SHM-stored object; really a regular-looking <code>shared_ptr</code> but with custom deleter that ensures deallocation via <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html" title="A SHM-classic interface around a single SHM pool with allocation-algorithm services by boost....">Pool_arena</a> as well as cross-process ref-count semantics.  <a href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a662a55c9ba6eb5c389ddf9780ee801cb">More...</a><br /></td></tr>
<tr class="separator:a662a55c9ba6eb5c389ddf9780ee801cb"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a72867ce6e363dbc1ab1666768d8a7a09"><td class="memItemLeft" align="right" valign="top">using&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a72867ce6e363dbc1ab1666768d8a7a09">Blob</a> = flow::util::Blob_sans_log_context</td></tr>
<tr class="memdesc:a72867ce6e363dbc1ab1666768d8a7a09"><td class="mdescLeft">&#160;</td><td class="mdescRight">Alias for a light-weight blob.  <a href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a72867ce6e363dbc1ab1666768d8a7a09">More...</a><br /></td></tr>
<tr class="separator:a72867ce6e363dbc1ab1666768d8a7a09"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="pub-methods" name="pub-methods"></a>
Public Member Functions</h2></td></tr>
<tr class="memitem:a0811a47ce0b29b86514313a4c6976dc1"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a0811a47ce0b29b86514313a4c6976dc1">Pool_arena</a> (flow::log::Logger *logger_ptr, const <a class="el" href="namespaceipc_1_1shm_1_1classic.html#ac0a52218467710995cc6c74538be6012">Shared_name</a> &amp;pool_name, <a class="el" href="namespaceipc_1_1util.html#a9d84c2bab504e6de32b20c77ca9723a2">util::Create_only</a> mode_tag, size_t pool_sz, const <a class="el" href="namespaceipc_1_1util.html#a1b398ae730d1e6040687cb2397115152">util::Permissions</a> &amp;perms=<a class="el" href="namespaceipc_1_1util.html#a1b398ae730d1e6040687cb2397115152">util::Permissions</a>(), <a class="el" href="namespaceipc.html#aa3192e586cc45d3e7c22463bf2760f89">Error_code</a> *err_code=0)</td></tr>
<tr class="memdesc:a0811a47ce0b29b86514313a4c6976dc1"><td class="mdescLeft">&#160;</td><td class="mdescRight">Construct <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html" title="A SHM-classic interface around a single SHM pool with allocation-algorithm services by boost....">Pool_arena</a> accessor object to non-existing named SHM pool, creating it first.  <a href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a0811a47ce0b29b86514313a4c6976dc1">More...</a><br /></td></tr>
<tr class="separator:a0811a47ce0b29b86514313a4c6976dc1"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:acb6ac11bcde9076bd121a0c61ef63159"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#acb6ac11bcde9076bd121a0c61ef63159">Pool_arena</a> (flow::log::Logger *logger_ptr, const <a class="el" href="namespaceipc_1_1shm_1_1classic.html#ac0a52218467710995cc6c74538be6012">Shared_name</a> &amp;pool_name, <a class="el" href="namespaceipc_1_1util.html#a9571de958538d7a4a8649bbfecfac0b9">util::Open_or_create</a> mode_tag, size_t pool_sz, const <a class="el" href="namespaceipc_1_1util.html#a1b398ae730d1e6040687cb2397115152">util::Permissions</a> &amp;perms_on_create=<a class="el" href="namespaceipc_1_1util.html#a1b398ae730d1e6040687cb2397115152">util::Permissions</a>(), <a class="el" href="namespaceipc.html#aa3192e586cc45d3e7c22463bf2760f89">Error_code</a> *err_code=0)</td></tr>
<tr class="memdesc:acb6ac11bcde9076bd121a0c61ef63159"><td class="mdescLeft">&#160;</td><td class="mdescRight">Construct <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html" title="A SHM-classic interface around a single SHM pool with allocation-algorithm services by boost....">Pool_arena</a> accessor object to non-existing named SHM pool, or else if it does not exist creates it first and opens it (atomically).  <a href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#acb6ac11bcde9076bd121a0c61ef63159">More...</a><br /></td></tr>
<tr class="separator:acb6ac11bcde9076bd121a0c61ef63159"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a49b84488d246ea5189f15d3f020e4d71"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a49b84488d246ea5189f15d3f020e4d71">Pool_arena</a> (flow::log::Logger *logger_ptr, const <a class="el" href="namespaceipc_1_1shm_1_1classic.html#ac0a52218467710995cc6c74538be6012">Shared_name</a> &amp;pool_name, <a class="el" href="namespaceipc_1_1util.html#a3e03491b5b2b5fac26551a220946d6e5">util::Open_only</a> mode_tag, bool read_only=false, <a class="el" href="namespaceipc.html#aa3192e586cc45d3e7c22463bf2760f89">Error_code</a> *err_code=0)</td></tr>
<tr class="memdesc:a49b84488d246ea5189f15d3f020e4d71"><td class="mdescLeft">&#160;</td><td class="mdescRight">Construct <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html" title="A SHM-classic interface around a single SHM pool with allocation-algorithm services by boost....">Pool_arena</a> accessor object to existing named SHM pool.  <a href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a49b84488d246ea5189f15d3f020e4d71">More...</a><br /></td></tr>
<tr class="separator:a49b84488d246ea5189f15d3f020e4d71"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:aca8bf9fe738df70fd502111330089c90"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#aca8bf9fe738df70fd502111330089c90">~Pool_arena</a> ()</td></tr>
<tr class="memdesc:aca8bf9fe738df70fd502111330089c90"><td class="mdescLeft">&#160;</td><td class="mdescRight">Destroys <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html" title="A SHM-classic interface around a single SHM pool with allocation-algorithm services by boost....">Pool_arena</a> accessor object.  <a href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#aca8bf9fe738df70fd502111330089c90">More...</a><br /></td></tr>
<tr class="separator:aca8bf9fe738df70fd502111330089c90"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a9da3a100a0b7199644edbadacc9083c9"><td class="memItemLeft" align="right" valign="top">void *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a9da3a100a0b7199644edbadacc9083c9">allocate</a> (size_t n)</td></tr>
<tr class="memdesc:a9da3a100a0b7199644edbadacc9083c9"><td class="mdescLeft">&#160;</td><td class="mdescRight">Allocates buffer of specified size, in bytes, in the accessed pool; returns locally-derefernceable address to the first byte.  <a href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a9da3a100a0b7199644edbadacc9083c9">More...</a><br /></td></tr>
<tr class="separator:a9da3a100a0b7199644edbadacc9083c9"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a394973b7cfb67b67113043810804337d"><td class="memItemLeft" align="right" valign="top">bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a394973b7cfb67b67113043810804337d">deallocate</a> (void *buf_not_null) noexcept</td></tr>
<tr class="memdesc:a394973b7cfb67b67113043810804337d"><td class="mdescLeft">&#160;</td><td class="mdescRight">Undoes effects of local <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a9da3a100a0b7199644edbadacc9083c9" title="Allocates buffer of specified size, in bytes, in the accessed pool; returns locally-derefernceable ad...">allocate()</a> that returned <code>buf_not_null</code>; or another-process's <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a9da3a100a0b7199644edbadacc9083c9" title="Allocates buffer of specified size, in bytes, in the accessed pool; returns locally-derefernceable ad...">allocate()</a> that returned pointer whose locally-dereferenceable equivalent is <code>but_not_null</code>.  <a href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a394973b7cfb67b67113043810804337d">More...</a><br /></td></tr>
<tr class="separator:a394973b7cfb67b67113043810804337d"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ab9f7ea056a55183d00dcbce573afcf36"><td class="memTemplParams" colspan="2">template&lt;typename T , typename... Ctor_args&gt; </td></tr>
<tr class="memitem:ab9f7ea056a55183d00dcbce573afcf36"><td class="memTemplItemLeft" align="right" valign="top"><a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a662a55c9ba6eb5c389ddf9780ee801cb">Handle</a>&lt; T &gt;&#160;</td><td class="memTemplItemRight" valign="bottom"><a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#ab9f7ea056a55183d00dcbce573afcf36">construct</a> (Ctor_args &amp;&amp;... ctor_args)</td></tr>
<tr class="memdesc:ab9f7ea056a55183d00dcbce573afcf36"><td class="mdescLeft">&#160;</td><td class="mdescRight">Constructs an object of given type with given ctor args, having allocated space directly in attached SHM pool, and returns a ref-counted handle that (1) guarantees destruction and deallocation shall occur once no owners hold a reference; and (2) can be lent to other processes (and other processes still indefinitely), thus adding owners beyond this process, via <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#acb300e64f92ab0aa5b70f8313c79a899" title="Adds an owner process to the owner count of the given construct()-created handle, and returns an opaq...">lend_object()</a>/borrow_object().  <a href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#ab9f7ea056a55183d00dcbce573afcf36">More...</a><br /></td></tr>
<tr class="separator:ab9f7ea056a55183d00dcbce573afcf36"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:acb300e64f92ab0aa5b70f8313c79a899"><td class="memTemplParams" colspan="2">template&lt;typename T &gt; </td></tr>
<tr class="memitem:acb300e64f92ab0aa5b70f8313c79a899"><td class="memTemplItemLeft" align="right" valign="top"><a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a72867ce6e363dbc1ab1666768d8a7a09">Blob</a>&#160;</td><td class="memTemplItemRight" valign="bottom"><a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#acb300e64f92ab0aa5b70f8313c79a899">lend_object</a> (const <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a662a55c9ba6eb5c389ddf9780ee801cb">Handle</a>&lt; T &gt; &amp;handle)</td></tr>
<tr class="memdesc:acb300e64f92ab0aa5b70f8313c79a899"><td class="mdescLeft">&#160;</td><td class="mdescRight">Adds an owner process to the owner count of the given <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#ab9f7ea056a55183d00dcbce573afcf36" title="Constructs an object of given type with given ctor args, having allocated space directly in attached ...">construct()</a>-created handle, and returns an opaque blob, such that if one passes it to <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#ad2f2b767d7da42e7e57592cc029386e5" title="Completes the cross-process operation begun by lend_object() that returned serialization; to be invok...">borrow_object()</a> in the receiving process, that <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#ad2f2b767d7da42e7e57592cc029386e5" title="Completes the cross-process operation begun by lend_object() that returned serialization; to be invok...">borrow_object()</a> shall return an equivalent <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a662a55c9ba6eb5c389ddf9780ee801cb" title="Outer handle to a SHM-stored object; really a regular-looking shared_ptr but with custom deleter that...">Handle</a> in that process.  <a href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#acb300e64f92ab0aa5b70f8313c79a899">More...</a><br /></td></tr>
<tr class="separator:acb300e64f92ab0aa5b70f8313c79a899"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ad2f2b767d7da42e7e57592cc029386e5"><td class="memTemplParams" colspan="2">template&lt;typename T &gt; </td></tr>
<tr class="memitem:ad2f2b767d7da42e7e57592cc029386e5"><td class="memTemplItemLeft" align="right" valign="top"><a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a662a55c9ba6eb5c389ddf9780ee801cb">Handle</a>&lt; T &gt;&#160;</td><td class="memTemplItemRight" valign="bottom"><a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#ad2f2b767d7da42e7e57592cc029386e5">borrow_object</a> (const <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a72867ce6e363dbc1ab1666768d8a7a09">Blob</a> &amp;serialization)</td></tr>
<tr class="memdesc:ad2f2b767d7da42e7e57592cc029386e5"><td class="mdescLeft">&#160;</td><td class="mdescRight">Completes the cross-process operation begun by <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#acb300e64f92ab0aa5b70f8313c79a899" title="Adds an owner process to the owner count of the given construct()-created handle, and returns an opaq...">lend_object()</a> that returned <code>serialization</code>; to be invoked in the intended new owner process.  <a href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#ad2f2b767d7da42e7e57592cc029386e5">More...</a><br /></td></tr>
<tr class="separator:ad2f2b767d7da42e7e57592cc029386e5"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ad2d54cc87b56613bba32aabd2c52ef13"><td class="memTemplParams" colspan="2">template&lt;typename T &gt; </td></tr>
<tr class="memitem:ad2d54cc87b56613bba32aabd2c52ef13"><td class="memTemplItemLeft" align="right" valign="top">bool&#160;</td><td class="memTemplItemRight" valign="bottom"><a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#ad2d54cc87b56613bba32aabd2c52ef13">is_handle_in_arena</a> (const <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a662a55c9ba6eb5c389ddf9780ee801cb">Handle</a>&lt; T &gt; &amp;handle) const</td></tr>
<tr class="memdesc:ad2d54cc87b56613bba32aabd2c52ef13"><td class="mdescLeft">&#160;</td><td class="mdescRight">Returns <code>true</code> if and only if <code>handle</code> came from either <code>this-&gt;construct&lt;T&gt;()</code> or <code>this-&gt;borrow_object&lt;T&gt;()</code>.  <a href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#ad2d54cc87b56613bba32aabd2c52ef13">More...</a><br /></td></tr>
<tr class="separator:ad2d54cc87b56613bba32aabd2c52ef13"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="pub-static-methods" name="pub-static-methods"></a>
Static Public Member Functions</h2></td></tr>
<tr class="memitem:aff2327ce7339c1c732ddd4fcd4861ee4"><td class="memItemLeft" align="right" valign="top">static void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#aff2327ce7339c1c732ddd4fcd4861ee4">remove_persistent</a> (flow::log::Logger *logger_ptr, const <a class="el" href="namespaceipc_1_1shm_1_1classic.html#ac0a52218467710995cc6c74538be6012">Shared_name</a> &amp;name, <a class="el" href="namespaceipc.html#aa3192e586cc45d3e7c22463bf2760f89">Error_code</a> *err_code=0)</td></tr>
<tr class="memdesc:aff2327ce7339c1c732ddd4fcd4861ee4"><td class="mdescLeft">&#160;</td><td class="mdescRight">Removes the named SHM pool object.  <a href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#aff2327ce7339c1c732ddd4fcd4861ee4">More...</a><br /></td></tr>
<tr class="separator:aff2327ce7339c1c732ddd4fcd4861ee4"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a9e720283945eefe3d941b185e95d2ce1"><td class="memTemplParams" colspan="2">template&lt;typename Handle_name_func &gt; </td></tr>
<tr class="memitem:a9e720283945eefe3d941b185e95d2ce1"><td class="memTemplItemLeft" align="right" valign="top">static void&#160;</td><td class="memTemplItemRight" valign="bottom"><a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a9e720283945eefe3d941b185e95d2ce1">for_each_persistent</a> (const Handle_name_func &amp;handle_name_func)</td></tr>
<tr class="memdesc:a9e720283945eefe3d941b185e95d2ce1"><td class="mdescLeft">&#160;</td><td class="mdescRight">Lists all named SHM pool objects currently persisting, invoking the given handler synchronously on each one.  <a href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a9e720283945eefe3d941b185e95d2ce1">More...</a><br /></td></tr>
<tr class="separator:a9e720283945eefe3d941b185e95d2ce1"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="pub-attribs" name="pub-attribs"></a>
Public Attributes</h2></td></tr>
<tr class="memitem:a71009bb725b4cd68bea4ac99fa81ee2e"><td class="memItemLeft" align="right" valign="top"><a id="a71009bb725b4cd68bea4ac99fa81ee2e" name="a71009bb725b4cd68bea4ac99fa81ee2e"></a>
const <a class="el" href="namespaceipc_1_1shm_1_1classic.html#ac0a52218467710995cc6c74538be6012">Shared_name</a>&#160;</td><td class="memItemRight" valign="bottom"><b>m_pool_name</b></td></tr>
<tr class="memdesc:a71009bb725b4cd68bea4ac99fa81ee2e"><td class="mdescLeft">&#160;</td><td class="mdescRight">SHM pool name as set immutably at construction. <br /></td></tr>
<tr class="separator:a71009bb725b4cd68bea4ac99fa81ee2e"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="related" name="related"></a>
Related Functions</h2></td></tr>
<tr><td class="ititle" colspan="2"><p >(Note that these are not member functions.) </p>
</td></tr>
<tr class="memitem:a4abe6573298da49d0914dd068a086f2c"><td class="memItemLeft" align="right" valign="top">std::ostream &amp;&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a4abe6573298da49d0914dd068a086f2c">operator&lt;&lt;</a> (std::ostream &amp;os, const <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html">Pool_arena</a> &amp;val)</td></tr>
<tr class="memdesc:a4abe6573298da49d0914dd068a086f2c"><td class="mdescLeft">&#160;</td><td class="mdescRight">Prints string representation of the given <code><a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html" title="A SHM-classic interface around a single SHM pool with allocation-algorithm services by boost....">Pool_arena</a></code> to the given <code>ostream</code>.  <a href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a4abe6573298da49d0914dd068a086f2c">More...</a><br /></td></tr>
<tr class="separator:a4abe6573298da49d0914dd068a086f2c"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<div class="textblock"><p >A SHM-classic interface around a single SHM pool with allocation-algorithm services by boost.interprocess, as in <code>bipc::managed_shared_memory</code>, with symmetric read/write semantics, compatible with <a class="el" href="namespaceipc_1_1shm_1_1stl.html" title="ipc::shm sub-module providing integration between STL-compliant components (including containers) and...">ipc::shm::stl</a> STL-compliance and SHM-handle borrowing manually or via <a class="el" href="namespaceipc_1_1session.html" title="Flow-IPC module providing the broad lifecycle and shared-resource organization – via the session conc...">ipc::session</a>. </p>
<h3>When to use</h3>
<p >Generally, this is a simple way to work with SHM. It is very easy to set up and has very little infrastructure on top of what is provided by a typically-used subset of bipc's SHM API &ndash; which, itself, is essentially a thin wrapper around a classic OS-supplied SHM pool (segment) API, plus a Boost-supplied heap-like allocation algorithm. Nevertheless this wrapper, when combined with <a class="el" href="namespaceipc_1_1shm_1_1stl.html" title="ipc::shm sub-module providing integration between STL-compliant components (including containers) and...">ipc::shm::stl</a>, is eminently usable and flexible. Its main limitations may or may not be serious in production use, depending on the context. These limitations include the following.</p><ul>
<li>When buffers are allocated and deallocated, bipc's default memory allocation algorithm &ndash; <code>rbtree_best_fit</code> &ndash; is what is used. (We could also allow for the other supplied algo, <code>simple_seq_fit</code>, or a custom user-supplied one.) While surely care was taken in writing this, in production one might demand something with thread caching and just general, like, industry relevance/experience; a jemalloc or tcmalloc maybe.<ul>
<li>Possible contingency: Not really. In many cases this does not matter too much; but if one wants general performance equal to that of the general heap in a loaded production environment, then <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html" title="A SHM-classic interface around a single SHM pool with allocation-algorithm services by boost....">classic::Pool_arena</a> is probably not for you. Consider jemalloc-based SHM provided elsewhere in <a class="el" href="namespaceipc_1_1shm.html" title="Modules for SHared Memory (SHM) support.">ipc::shm</a>.</li>
</ul>
</li>
<li>It works within exactly one <em>pool</em> a/k/a <code>mmap()</code>ped segment, and that pool's max size must be specified at creation. Once it is exhausted via un-deallocated allocations, it'll throw exceptions likely to wreak havoc in your application.<ul>
<li>Possible contingency: You may set the max pool size to a giant value. This will <em>not</em> take it from the OS like Linux: only when a page is actually touched, such as by allocating in it, does that actual RAM get assigned to your application(s). There is unfortunately, at least in Linux, some configurable kernel parameters as to the sum of max pool sizes active at a given time &ndash; <code>ENOSPC</code> (No space left on device) may be emitted when trying to open a pool beyond this. All in all it is a viable approach but may need a measure of finesse.</li>
</ul>
</li>
<li>The ability to allocate in a given backing pool via any process's <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html" title="A SHM-classic interface around a single SHM pool with allocation-algorithm services by boost....">Pool_arena</a> handle to that backing pool &ndash; not to mention deallocate in process B what was allocated in process A &ndash; requires guaranteed read-write capability in all <code><a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html" title="A SHM-classic interface around a single SHM pool with allocation-algorithm services by boost....">Pool_arena</a></code>s accessing a given pool. That read-write capability in and of itself (orthogonally to allocations) provides algorithmic possibilities which are not easily available in an asymmetric setup, where only one process can write or deallocate, while others can only borrow handles and read. How is this a limitation, you ask? While providing power and simplicity, it also hugely increases the number and difficulty of dealing with unexpected conditions. That is &ndash; any process can write and corrupt the pool's contents, thus "poisoning" other processes; any process crashing means the others cannot trust the integrity of the pool's contents; things of that nature.<ul>
<li>Possible contingency: It would not be difficult to enable read-only access from all but one process; we provide such a constructor argument. However, one cannot use the SHM-handle borrowing method <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#ad2f2b767d7da42e7e57592cc029386e5" title="Completes the cross-process operation begun by lend_object() that returned serialization; to be invok...">borrow_object()</a> which severely stunts the usefulness of the class in that process and therefore across the system. That said one could imagine somewhat extending <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html" title="A SHM-classic interface around a single SHM pool with allocation-algorithm services by boost....">Pool_arena</a> to enable lend-borrow and delegated deallocation (and maybe delegated allocation while at it) by adding some internal message-passing (maybe through a supplied <a class="el" href="classipc_1_1transport_1_1Channel.html" title="Peer to a bundle of 1-2 full-duplex pipe(s), one for transmitting unstructured binary blobs; the othe...">transport::Channel</a> or something). Doable but frankly goes against the spirit of simplicty and closeness-to-the-"source-material" cultivated by <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html" title="A SHM-classic interface around a single SHM pool with allocation-algorithm services by boost....">classic::Pool_arena</a>. The jemalloc-based API available elsewhere in <a class="el" href="namespaceipc_1_1shm.html" title="Modules for SHared Memory (SHM) support.">ipc::shm</a> is the one that happily performs message-passing IPC internally for such reasons. It's a thought though.</li>
</ul>
</li>
</ul>
<h3>Properties</h3>
<p >Backing pool structure: One (1) SHM pool, explicitly named at construction. Can open handle with create-only, create-or-open (atomic), or open-only semantics. Pool size specified at construction/cannot be changed. Vaddr structure is not synchronized (so <code>void* p</code> pointing into SHM in process 1 cannot be used in process 2 without first adjusting it based on the different base vaddr of the mapped pool in process 2 versus 1).</p>
<p >Handle-to-arena structure: <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html" title="A SHM-classic interface around a single SHM pool with allocation-algorithm services by boost....">Pool_arena</a> is the only type, used by any process involved, that accesses the underlying arena, and once open all capabilities are symmetrically available to all <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html" title="A SHM-classic interface around a single SHM pool with allocation-algorithm services by boost....">Pool_arena</a> objects in all processes.</p><ul>
<li>Any <code><a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html" title="A SHM-classic interface around a single SHM pool with allocation-algorithm services by boost....">Pool_arena</a></code> can allocate (and deallocate what it has allocated).</li>
<li>Any <code><a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html" title="A SHM-classic interface around a single SHM pool with allocation-algorithm services by boost....">Pool_arena</a></code> can deallocate what any other <code><a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html" title="A SHM-classic interface around a single SHM pool with allocation-algorithm services by boost....">Pool_arena</a></code> has allocated (as long as the correct locally-dereferenceable <code>void*</code> has been obtained in the deallocating process).</li>
</ul>
<p >Allocation algorithm: As of this writing the bipc default, <code>rbtree_best_fit</code>. See its description in bipc docs. Note it does not perform any thread-caching like modern <code>malloc()</code>s.</p>
<p >Allocation/deallocation API: See section below for proper use techniques.</p>
<p >Cleanup: The underlying SHM pool is deleted if and only if one calls <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#aff2327ce7339c1c732ddd4fcd4861ee4" title="Removes the named SHM pool object.">remove_persistent()</a>, supplying it the pool name. This is not invoked internally at all, so it is the user's responsibility. <a class="el" href="namespaceipc_1_1session.html" title="Flow-IPC module providing the broad lifecycle and shared-resource organization – via the session conc...">ipc::session</a>-managed <code><a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html" title="A SHM-classic interface around a single SHM pool with allocation-algorithm services by boost....">Pool_arena</a></code>s will be automatically cleaned up, as <a class="el" href="namespaceipc_1_1session.html" title="Flow-IPC module providing the broad lifecycle and shared-resource organization – via the session conc...">ipc::session</a> strives to clean all persistent shared resources via a general algorithm. See <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#aff2327ce7339c1c732ddd4fcd4861ee4" title="Removes the named SHM pool object.">remove_persistent()</a> and <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a9e720283945eefe3d941b185e95d2ce1" title="Lists all named SHM pool objects currently persisting, invoking the given handler synchronously on ea...">for_each_persistent()</a> doc headers.</p>
<p >Satisfies <code>Arena</code> requirements for <a class="el" href="classipc_1_1shm_1_1stl_1_1Stateless__allocator.html" title="Stateless allocator usable with STL-compliant containers to store (or merely read) them directly in S...">shm::stl::Stateless_allocator</a>: Yes. I.e., it is easy to store STL-compliant containers directly in SHM by using <code>Stateless_allocator&lt;<a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html" title="A SHM-classic interface around a single SHM pool with allocation-algorithm services by boost....">Pool_arena</a>&gt;</code> as the allocator at all levels.</p><ul>
<li>SHM-stored pointer type provided: Yes, <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a07fec7ff0ba494dca0f0a010270cc35f" title="SHM-storable fancy-pointer.">Pointer</a>. This is, in reality, <code>bipc::offset_ptr</code>.</li>
<li>Non-STL-compliant data structures with pointers, such as linked lists, can be written in terms of <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a9da3a100a0b7199644edbadacc9083c9" title="Allocates buffer of specified size, in bytes, in the accessed pool; returns locally-derefernceable ad...">allocate()</a> and <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a394973b7cfb67b67113043810804337d" title="Undoes effects of local allocate() that returned buf_not_null; or another-process&#39;s allocate() that r...">deallocate()</a>, but only if one uses <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a07fec7ff0ba494dca0f0a010270cc35f" title="SHM-storable fancy-pointer.">Pointer</a> as opposed to raw <code>T*</code> pointers. We recommend against this, but if it cannot be avoided due to legacy code or what-not....</li>
</ul>
<p >Handle borrowing support: Yes. <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html" title="A SHM-classic interface around a single SHM pool with allocation-algorithm services by boost....">Pool_arena</a> directly provides an API for this. Internally it uses minimalistic atomic ref-counting directly in SHM without any IPC messaging used. Due to this internal simplicity this support is symmetric and supports unlimited proxying out of the box. That is, any process of N, each with a <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html" title="A SHM-classic interface around a single SHM pool with allocation-algorithm services by boost....">Pool_arena</a> open to the same pool named P, can construct a borrowable object, then lend it to any other process which can also lend it to any other of the N processes. Internally the last <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html" title="A SHM-classic interface around a single SHM pool with allocation-algorithm services by boost....">Pool_arena</a>'s borrowed (or originally lent) handle to reach 0 intra-process ref-count shall invoke the object's dtor and deallocate the underlying buffer. (Algorithms like this = why symmetric read/write capability is fairly central to <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html" title="A SHM-classic interface around a single SHM pool with allocation-algorithm services by boost....">Pool_arena</a> as written.)</p><ul>
<li>However, as of this writing, this support is deliberately basic. In particular if a borrower process dies ungracefully (crash that does not execute all destructors, and so on), then the memory will leak until cleanup via <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#aff2327ce7339c1c732ddd4fcd4861ee4" title="Removes the named SHM pool object.">remove_persistent()</a>.</li>
</ul>
<h3>Allocation API and how to properly use it</h3>
<p >The most basic and lowest-level API consists of <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a9da3a100a0b7199644edbadacc9083c9" title="Allocates buffer of specified size, in bytes, in the accessed pool; returns locally-derefernceable ad...">allocate()</a> and <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a394973b7cfb67b67113043810804337d" title="Undoes effects of local allocate() that returned buf_not_null; or another-process&#39;s allocate() that r...">deallocate()</a>. We recommend against user code using these, as it is easy to leak and double-free (same as with <code>new</code> and <code>delete</code> in regular heap, except as usual with SHM anything that was not allocated will persist in RAM until <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#aff2327ce7339c1c732ddd4fcd4861ee4" title="Removes the named SHM pool object.">remove_persistent()</a>).</p><ul>
<li><a class="el" href="namespaceipc_1_1shm_1_1stl.html" title="ipc::shm sub-module providing integration between STL-compliant components (including containers) and...">shm::stl</a> allocator(s) will use these APIs safely.</li>
<li>As noted earlier, if one writes a non-STL-compliant data structure (such as a manually written linked list), it is appropriate to use <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a9da3a100a0b7199644edbadacc9083c9" title="Allocates buffer of specified size, in bytes, in the accessed pool; returns locally-derefernceable ad...">allocate()</a>, <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a394973b7cfb67b67113043810804337d" title="Undoes effects of local allocate() that returned buf_not_null; or another-process&#39;s allocate() that r...">deallocate()</a>, and <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a07fec7ff0ba494dca0f0a010270cc35f" title="SHM-storable fancy-pointer.">Pointer</a>. It is best to avoid such data structures in favor of <a class="el" href="namespaceipc_1_1shm_1_1stl.html" title="ipc::shm sub-module providing integration between STL-compliant components (including containers) and...">shm::stl</a>-aided STL-compliant structures.</li>
</ul>
<p >The next level of API is <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#ab9f7ea056a55183d00dcbce573afcf36" title="Constructs an object of given type with given ctor args, having allocated space directly in attached ...">construct()</a>. <code>construct&lt;T&gt;()</code> returns a regular-looking <code>shared_ptr</code>. If it is never lent to another process, then the constructed <code>T</code> will be destroyed automatically as one would expect. If one <em>does</em> properly lend such a <code>shared_ptr</code> (which we call a <em>handle</em>) to another process (and which it can proxy-lend to another process still), then the <code>T</code> will be destroyed by the last process whose handle reaches ref-count 0. No explicit locking on the user's part is required to make this work.</p><ul>
<li>If <code>T</code> is a POD (plain old data-type), then that's that.</li>
<li>If not, but <code>T</code> is a <a class="el" href="namespaceipc_1_1shm_1_1stl.html" title="ipc::shm sub-module providing integration between STL-compliant components (including containers) and...">shm::stl</a>-allocator-aided STL-compliant-structure, then you're good.</li>
<li>If not (e.g., the aforementioned manually implemented linked list) but the <code>T</code> destructor performs the necessary inner deallocation via <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a394973b7cfb67b67113043810804337d" title="Undoes effects of local allocate() that returned buf_not_null; or another-process&#39;s allocate() that r...">deallocate()</a>, then you're good. Again, we recommend against this, but sometimes it cannot be helped.</li>
<li>If not, then one must manually do the inner deallocation first, then let the handle (<code>shared_ptr</code>) group reach ref-count 0. The key is to do it in that order (which is why doing it via <code>T::~T()</code> is easiest).</li>
</ul>
<p ><code>T</code> cannot be a native array; and there is no facility for constructing such. Use <code>std::array</code> or <code>boost::array</code> as <code>T</code> if desired. </p>
</div><h2 class="groupheader">Member Typedef Documentation</h2>
<a id="a72867ce6e363dbc1ab1666768d8a7a09" name="a72867ce6e363dbc1ab1666768d8a7a09"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a72867ce6e363dbc1ab1666768d8a7a09">&#9670;&nbsp;</a></span>Blob</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">using <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a72867ce6e363dbc1ab1666768d8a7a09">ipc::shm::classic::Pool_arena::Blob</a> =  flow::util::Blob_sans_log_context</td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Alias for a light-weight blob. </p>
<p >They're little; TRACE-logging of deallocs and copies is of low value; otherwise this can be switched to <code>flow::util::Blob</code>. </p>

</div>
</div>
<a id="a662a55c9ba6eb5c389ddf9780ee801cb" name="a662a55c9ba6eb5c389ddf9780ee801cb"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a662a55c9ba6eb5c389ddf9780ee801cb">&#9670;&nbsp;</a></span>Handle</h2>

<div class="memitem">
<div class="memproto">
<div class="memtemplate">
template&lt;typename T &gt; </div>
      <table class="memname">
        <tr>
          <td class="memname">using <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a662a55c9ba6eb5c389ddf9780ee801cb">ipc::shm::classic::Pool_arena::Handle</a> =  boost::shared_ptr&lt;T&gt;</td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Outer handle to a SHM-stored object; really a regular-looking <code>shared_ptr</code> but with custom deleter that ensures deallocation via <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html" title="A SHM-classic interface around a single SHM pool with allocation-algorithm services by boost....">Pool_arena</a> as well as cross-process ref-count semantics. </p>
<p >See class doc header and <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#ab9f7ea056a55183d00dcbce573afcf36" title="Constructs an object of given type with given ctor args, having allocated space directly in attached ...">construct()</a>. A handle can also be lent/borrowed between processes; see <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#acb300e64f92ab0aa5b70f8313c79a899" title="Adds an owner process to the owner count of the given construct()-created handle, and returns an opaq...">lend_object()</a> and <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#ad2f2b767d7da42e7e57592cc029386e5" title="Completes the cross-process operation begun by lend_object() that returned serialization; to be invok...">borrow_object()</a>.</p>
<h3>Rationale</h3>
<p >Why have an alias, where it's a mere <code>shared_ptr</code>? Two-fold reason:</p><ul>
<li>(Mostly) While it <em>is</em> just <code>shared_ptr&lt;T&gt;</code>, and acts just as one would expect if <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#ad2f2b767d7da42e7e57592cc029386e5" title="Completes the cross-process operation begun by lend_object() that returned serialization; to be invok...">borrow_object()</a> and <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#acb300e64f92ab0aa5b70f8313c79a899" title="Adds an owner process to the owner count of the given construct()-created handle, and returns an opaq...">lend_object()</a> are not involved, (1) it is an <em>outer</em> handle to a SHM-stored object, unlike the inner (subordinate) <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a07fec7ff0ba494dca0f0a010270cc35f" title="SHM-storable fancy-pointer.">Pointer</a> values as maintained by STL-compliant logic or other data structure-internals code; and (2) it has special (if hopefully quite intuitive) capabilities of invoking ref-counting "across" processes via <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#acb300e64f92ab0aa5b70f8313c79a899" title="Adds an owner process to the owner count of the given construct()-created handle, and returns an opaq...">lend_object()</a> and <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#ad2f2b767d7da42e7e57592cc029386e5" title="Completes the cross-process operation begun by lend_object() that returned serialization; to be invok...">borrow_object()</a>.</li>
<li>(Minor) It's nice not to visibly impose a particular <code>shared_ptr</code> impl but kinda hide it behind an alias. Ahem....</li>
</ul>
<dl class="tparams"><dt>Template Parameters</dt><dd>
  <table class="tparams">
    <tr><td class="paramname">T</td><td>The pointed-to type. Its dtor, informally, should ensure any inner deallocations subordinate to the managed <code>T</code> are performed before the <code>shared_ptr</code> reaches ref-count 0 in all processes to get the handle. See class doc header. </td></tr>
  </table>
  </dd>
</dl>

</div>
</div>
<a id="a07fec7ff0ba494dca0f0a010270cc35f" name="a07fec7ff0ba494dca0f0a010270cc35f"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a07fec7ff0ba494dca0f0a010270cc35f">&#9670;&nbsp;</a></span>Pointer</h2>

<div class="memitem">
<div class="memproto">
<div class="memtemplate">
template&lt;typename T &gt; </div>
      <table class="memname">
        <tr>
          <td class="memname">using <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a07fec7ff0ba494dca0f0a010270cc35f">ipc::shm::classic::Pool_arena::Pointer</a> =  ::ipc::bipc::offset_ptr&lt;T&gt;</td>
        </tr>
      </table>
</div><div class="memdoc">

<p>SHM-storable fancy-pointer. </p>
<p >See class doc header for discussion. Suitable for <a class="el" href="namespaceipc_1_1shm_1_1stl.html" title="ipc::shm sub-module providing integration between STL-compliant components (including containers) and...">shm::stl</a> allocator(s).</p>
<dl class="tparams"><dt>Template Parameters</dt><dd>
  <table class="tparams">
    <tr><td class="paramname">T</td><td>The pointed-to type. <code>Pointer&lt;T&gt;</code> acts like <code>T*</code>. </td></tr>
  </table>
  </dd>
</dl>

</div>
</div>
<h2 class="groupheader">Constructor &amp; Destructor Documentation</h2>
<a id="a0811a47ce0b29b86514313a4c6976dc1" name="a0811a47ce0b29b86514313a4c6976dc1"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a0811a47ce0b29b86514313a4c6976dc1">&#9670;&nbsp;</a></span>Pool_arena() <span class="overload">[1/3]</span></h2>

<div class="memitem">
<div class="memproto">
<table class="mlabels">
  <tr>
  <td class="mlabels-left">
      <table class="memname">
        <tr>
          <td class="memname">ipc::shm::classic::Pool_arena::Pool_arena </td>
          <td>(</td>
          <td class="paramtype">flow::log::Logger *&#160;</td>
          <td class="paramname"><em>logger_ptr</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">const <a class="el" href="namespaceipc_1_1shm_1_1classic.html#ac0a52218467710995cc6c74538be6012">Shared_name</a> &amp;&#160;</td>
          <td class="paramname"><em>pool_name</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype"><a class="el" href="namespaceipc_1_1util.html#a9d84c2bab504e6de32b20c77ca9723a2">util::Create_only</a>&#160;</td>
          <td class="paramname"><em>mode_tag</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">size_t&#160;</td>
          <td class="paramname"><em>pool_sz</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">const <a class="el" href="namespaceipc_1_1util.html#a1b398ae730d1e6040687cb2397115152">util::Permissions</a> &amp;&#160;</td>
          <td class="paramname"><em>perms</em> = <code><a class="el" href="namespaceipc_1_1util.html#a1b398ae730d1e6040687cb2397115152">util::Permissions</a>()</code>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype"><a class="el" href="namespaceipc.html#aa3192e586cc45d3e7c22463bf2760f89">Error_code</a> *&#160;</td>
          <td class="paramname"><em>err_code</em> = <code>0</code>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
  </td>
  <td class="mlabels-right">
<span class="mlabels"><span class="mlabel">explicit</span></span>  </td>
  </tr>
</table>
</div><div class="memdoc">

<p>Construct <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html" title="A SHM-classic interface around a single SHM pool with allocation-algorithm services by boost....">Pool_arena</a> accessor object to non-existing named SHM pool, creating it first. </p>
<p >If it already exists, it is an error. If an error is emitted via <code>*err_code</code>, methods shall return sentinel/<code>false</code> values.</p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">logger_ptr</td><td>Logger to use for subsequently logging. </td></tr>
    <tr><td class="paramname">pool_name</td><td>Absolute name at which the persistent SHM pool lives. </td></tr>
    <tr><td class="paramname">mode_tag</td><td>API-choosing tag <a class="el" href="namespaceipc_1_1util.html#ad1ca1cab79a35e1eb1c47037a0973cd8" title="Tag value indicating an atomic create-unless-exists-else-fail operation.">util::CREATE_ONLY</a>. </td></tr>
    <tr><td class="paramname">perms</td><td>Permissions to use for creation. Suggest the use of <a class="el" href="namespaceipc_1_1util.html#abda2ce5bcdbc26ca63d667b87818439c" title="Maps general Permissions_level specifier to low-level Permissions value, when the underlying resource...">util::shared_resource_permissions()</a> to translate from one of a small handful of levels of access; these apply almost always in practice. The applied permissions shall <em>ignore</em> the process umask and shall thus exactly match <code>perms</code>, unless an error occurs. </td></tr>
    <tr><td class="paramname">pool_sz</td><td>Pool size. Note: OS, namely Linux, shall not in fact take (necessarily) this full amount from general availability but rather a small amount. Chunks of RAM (pages) shall be later reserved as they begin to be used, namely via the allocation API. It may be viable to set this to a quite large value to avoid running out of pool space. However watch out for (typically configurable) kernel parameters as to the sum of sizes of active pools. </td></tr>
    <tr><td class="paramname">err_code</td><td>See <code>flow::Error_code</code> docs for error reporting semantics. <a class="el" href="namespaceipc.html#aa3192e586cc45d3e7c22463bf2760f89" title="Short-hand for flow::Error_code which is very common.">Error_code</a> generated: various. Most likely creation failed due to permissions, or it already existed. An <code>ENOSPC</code> (No space left on device) error means the aforementioned kernel parameter has been hit (Linux at least); pool size rebalancing in your overall system may be required (or else one might tweak the relevant kernel parameter(s)). </td></tr>
  </table>
  </dd>
</dl>

</div>
</div>
<a id="acb6ac11bcde9076bd121a0c61ef63159" name="acb6ac11bcde9076bd121a0c61ef63159"></a>
<h2 class="memtitle"><span class="permalink"><a href="#acb6ac11bcde9076bd121a0c61ef63159">&#9670;&nbsp;</a></span>Pool_arena() <span class="overload">[2/3]</span></h2>

<div class="memitem">
<div class="memproto">
<table class="mlabels">
  <tr>
  <td class="mlabels-left">
      <table class="memname">
        <tr>
          <td class="memname">ipc::shm::classic::Pool_arena::Pool_arena </td>
          <td>(</td>
          <td class="paramtype">flow::log::Logger *&#160;</td>
          <td class="paramname"><em>logger_ptr</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">const <a class="el" href="namespaceipc_1_1shm_1_1classic.html#ac0a52218467710995cc6c74538be6012">Shared_name</a> &amp;&#160;</td>
          <td class="paramname"><em>pool_name</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype"><a class="el" href="namespaceipc_1_1util.html#a9571de958538d7a4a8649bbfecfac0b9">util::Open_or_create</a>&#160;</td>
          <td class="paramname"><em>mode_tag</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">size_t&#160;</td>
          <td class="paramname"><em>pool_sz</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">const <a class="el" href="namespaceipc_1_1util.html#a1b398ae730d1e6040687cb2397115152">util::Permissions</a> &amp;&#160;</td>
          <td class="paramname"><em>perms_on_create</em> = <code><a class="el" href="namespaceipc_1_1util.html#a1b398ae730d1e6040687cb2397115152">util::Permissions</a>()</code>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype"><a class="el" href="namespaceipc.html#aa3192e586cc45d3e7c22463bf2760f89">Error_code</a> *&#160;</td>
          <td class="paramname"><em>err_code</em> = <code>0</code>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
  </td>
  <td class="mlabels-right">
<span class="mlabels"><span class="mlabel">explicit</span></span>  </td>
  </tr>
</table>
</div><div class="memdoc">

<p>Construct <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html" title="A SHM-classic interface around a single SHM pool with allocation-algorithm services by boost....">Pool_arena</a> accessor object to non-existing named SHM pool, or else if it does not exist creates it first and opens it (atomically). </p>
<p >If an error is emitted via <code>*err_code</code>, methods shall return sentinel/<code>false</code> values.</p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">logger_ptr</td><td>Logger to use for subsequently logging. </td></tr>
    <tr><td class="paramname">pool_name</td><td>Absolute name at which the persistent SHM pool lives. </td></tr>
    <tr><td class="paramname">mode_tag</td><td>API-choosing tag <a class="el" href="namespaceipc_1_1util.html#a5664539b3d75d6d10cdfebf6eac5382d" title="Tag value indicating an open-if-exists-else-create operation.">util::OPEN_OR_CREATE</a>. </td></tr>
    <tr><td class="paramname">perms_on_create</td><td>Permissions to use for creation. Suggest the use of <a class="el" href="namespaceipc_1_1util.html#abda2ce5bcdbc26ca63d667b87818439c" title="Maps general Permissions_level specifier to low-level Permissions value, when the underlying resource...">util::shared_resource_permissions()</a> to translate from one of a small handful of levels of access; these apply almost always in practice. The applied permissions shall <em>ignore</em> the process umask and shall thus exactly match <code>perms_on_create</code>, unless an error occurs. </td></tr>
    <tr><td class="paramname">pool_sz</td><td>Pool size. See note in first ctor. </td></tr>
    <tr><td class="paramname">err_code</td><td>See <code>flow::Error_code</code> docs for error reporting semantics. <a class="el" href="namespaceipc.html#aa3192e586cc45d3e7c22463bf2760f89" title="Short-hand for flow::Error_code which is very common.">Error_code</a> generated: various. Most likely creation failed due to permissions, or it already existed. </td></tr>
  </table>
  </dd>
</dl>

</div>
</div>
<a id="a49b84488d246ea5189f15d3f020e4d71" name="a49b84488d246ea5189f15d3f020e4d71"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a49b84488d246ea5189f15d3f020e4d71">&#9670;&nbsp;</a></span>Pool_arena() <span class="overload">[3/3]</span></h2>

<div class="memitem">
<div class="memproto">
<table class="mlabels">
  <tr>
  <td class="mlabels-left">
      <table class="memname">
        <tr>
          <td class="memname">ipc::shm::classic::Pool_arena::Pool_arena </td>
          <td>(</td>
          <td class="paramtype">flow::log::Logger *&#160;</td>
          <td class="paramname"><em>logger_ptr</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">const <a class="el" href="namespaceipc_1_1shm_1_1classic.html#ac0a52218467710995cc6c74538be6012">Shared_name</a> &amp;&#160;</td>
          <td class="paramname"><em>pool_name</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype"><a class="el" href="namespaceipc_1_1util.html#a3e03491b5b2b5fac26551a220946d6e5">util::Open_only</a>&#160;</td>
          <td class="paramname"><em>mode_tag</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">bool&#160;</td>
          <td class="paramname"><em>read_only</em> = <code>false</code>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype"><a class="el" href="namespaceipc.html#aa3192e586cc45d3e7c22463bf2760f89">Error_code</a> *&#160;</td>
          <td class="paramname"><em>err_code</em> = <code>0</code>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
  </td>
  <td class="mlabels-right">
<span class="mlabels"><span class="mlabel">explicit</span></span>  </td>
  </tr>
</table>
</div><div class="memdoc">

<p>Construct <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html" title="A SHM-classic interface around a single SHM pool with allocation-algorithm services by boost....">Pool_arena</a> accessor object to existing named SHM pool. </p>
<p >If it does not exist, it is an error. If an error is emitted via <code>*err_code</code>, methods shall return sentinel/<code>false</code> values.</p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">logger_ptr</td><td>Logger to use for subsequently logging. </td></tr>
    <tr><td class="paramname">pool_name</td><td>Absolute name at which the persistent SHM pool lives. </td></tr>
    <tr><td class="paramname">mode_tag</td><td>API-choosing tag <a class="el" href="namespaceipc_1_1util.html#a6a3a6ec85242d073df96978c63464078" title="Tag value indicating an atomic open-if-exists-else-fail operation.">util::OPEN_ONLY</a>. </td></tr>
    <tr><td class="paramname">read_only</td><td>If and only if <code>true</code> the calling process will be prevented by the OS from writing into the pages mapped by <code>*this</code> subsequently. Such attempts will lead to undefined behavior. Note that this includes any attempt at allocating as well as writing into allocated (or otherwise) address space. Further note that, internally, deallocation &ndash; directly or otherwise &ndash; involves (in this implementation) writing and is thus also disallowed. Lastly, and quite significantly, <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#ad2f2b767d7da42e7e57592cc029386e5" title="Completes the cross-process operation begun by lend_object() that returned serialization; to be invok...">borrow_object()</a> can be called, but undefined behavior shall result when the resulting <code>shared_ptr</code> (<a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a662a55c9ba6eb5c389ddf9780ee801cb" title="Outer handle to a SHM-stored object; really a regular-looking shared_ptr but with custom deleter that...">Handle</a>) group reaches ref-count 0, as internally that requires a decrement of a counter (which is a write). Therefore <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#ad2f2b767d7da42e7e57592cc029386e5" title="Completes the cross-process operation begun by lend_object() that returned serialization; to be invok...">borrow_object()</a> cannot be used either. Therefore it is up to you, in that case, to (1) never call <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a394973b7cfb67b67113043810804337d" title="Undoes effects of local allocate() that returned buf_not_null; or another-process&#39;s allocate() that r...">deallocate()</a> directly or otherwise (i.e., through an allocator); and (2) to design your algorithms in such a way as to never require lending to this <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html" title="A SHM-classic interface around a single SHM pool with allocation-algorithm services by boost....">Pool_arena</a>. In practice this would be quite a low-level, stunted use of <code><a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html" title="A SHM-classic interface around a single SHM pool with allocation-algorithm services by boost....">Pool_arena</a></code> across 2+ processes; but it is not necessarily useless. (There might be, say, test/debug/reporting use cases.) </td></tr>
    <tr><td class="paramname">err_code</td><td>See <code>flow::Error_code</code> docs for error reporting semantics. <a class="el" href="namespaceipc.html#aa3192e586cc45d3e7c22463bf2760f89" title="Short-hand for flow::Error_code which is very common.">Error_code</a> generated: various. Most likely creation failed due to permissions, or it already existed. </td></tr>
  </table>
  </dd>
</dl>

</div>
</div>
<a id="aca8bf9fe738df70fd502111330089c90" name="aca8bf9fe738df70fd502111330089c90"></a>
<h2 class="memtitle"><span class="permalink"><a href="#aca8bf9fe738df70fd502111330089c90">&#9670;&nbsp;</a></span>~Pool_arena()</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">ipc::shm::classic::Pool_arena::~Pool_arena </td>
          <td>(</td>
          <td class="paramname"></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Destroys <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html" title="A SHM-classic interface around a single SHM pool with allocation-algorithm services by boost....">Pool_arena</a> accessor object. </p>
<p >In and of itself this does not destroy the underlying pool named <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a71009bb725b4cd68bea4ac99fa81ee2e" title="SHM pool name as set immutably at construction.">m_pool_name</a>; it continues to exist as long as (1) any other similar accessor objects (or other OS-created handles) do; and/or (2) its entry in the file system lives (hence until <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#aff2327ce7339c1c732ddd4fcd4861ee4" title="Removes the named SHM pool object.">remove_persistent()</a> is called for <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a71009bb725b4cd68bea4ac99fa81ee2e" title="SHM pool name as set immutably at construction.">m_pool_name</a>). This is analogous to closing a descriptor to a file. </p>

</div>
</div>
<h2 class="groupheader">Member Function Documentation</h2>
<a id="a9da3a100a0b7199644edbadacc9083c9" name="a9da3a100a0b7199644edbadacc9083c9"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a9da3a100a0b7199644edbadacc9083c9">&#9670;&nbsp;</a></span>allocate()</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">void * ipc::shm::classic::Pool_arena::allocate </td>
          <td>(</td>
          <td class="paramtype">size_t&#160;</td>
          <td class="paramname"><em>n</em></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Allocates buffer of specified size, in bytes, in the accessed pool; returns locally-derefernceable address to the first byte. </p>
<p >Returns null if no pool attached to <code>*this</code>. Throws exception if ran out of space.</p>
<p >Take care to only use this when and as appropriate; see class doc header notes on this.</p>
<h3>Rationale for throwing exception instead of returning null</h3>
<p >This does go against the precedent in most of <a class="el" href="namespaceipc.html" title="Catch-all namespace for the Flow-IPC project: A library/API in modern C++17 providing high-performanc...">ipc</a>, which either returns sentinel values or uses Flow-style <a class="el" href="namespaceipc.html#aa3192e586cc45d3e7c22463bf2760f89" title="Short-hand for flow::Error_code which is very common.">Error_code</a> based emission (out-arg or exception). The original reason may appear somewhat arbitrary and is 2-fold:</p><ul>
<li>It's what bipc does (throws <code>bipc::bad_alloc_exception</code>), and indeed we propagate what it throws.</li>
<li>It's what STL-compliant allocators (such as our own in <a class="el" href="namespaceipc_1_1shm_1_1stl.html" title="ipc::shm sub-module providing integration between STL-compliant components (including containers) and...">shm::stl</a>) must do; and they will invoke this (certainly not exclusively).</li>
</ul>
<p >I (ygoldfel) claim it's a matter of... synergy, maybe, or tradition. It really is an exceptional situation to run out of pool space. Supposing some system is built on-top of N pools, of which <code>*this</code> is one, it can certainly catch it (and in that case it shouldn't be frequent enough to seriously affect perf by virtue of slowness of exception-throwing/catching) and use another pool. Granted, it could use Flow semantics, which would throw only if an <code>Error_code*</code> supplied were null, but that misses the point that <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a9da3a100a0b7199644edbadacc9083c9" title="Allocates buffer of specified size, in bytes, in the accessed pool; returns locally-derefernceable ad...">allocate()</a> failing to allocate due to lack of space is the only thing that can really go wrong and is exceptional. Adding an <code>Error_code* err_code</code> out-arg would hardly add much value.</p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">n</td><td>Desired buffer size in bytes. Must not be 0 (behavior undefined/assertion may trip). </td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Non-null on success (see above); null if ctor failed to attach pool. </dd></dl>

</div>
</div>
<a id="ad2f2b767d7da42e7e57592cc029386e5" name="ad2f2b767d7da42e7e57592cc029386e5"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ad2f2b767d7da42e7e57592cc029386e5">&#9670;&nbsp;</a></span>borrow_object()</h2>

<div class="memitem">
<div class="memproto">
<div class="memtemplate">
template&lt;typename T &gt; </div>
      <table class="memname">
        <tr>
          <td class="memname"><a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a662a55c9ba6eb5c389ddf9780ee801cb">Pool_arena::Handle</a>&lt; T &gt; ipc::shm::classic::Pool_arena::borrow_object </td>
          <td>(</td>
          <td class="paramtype">const <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a72867ce6e363dbc1ab1666768d8a7a09">Blob</a> &amp;&#160;</td>
          <td class="paramname"><em>serialization</em></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Completes the cross-process operation begun by <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#acb300e64f92ab0aa5b70f8313c79a899" title="Adds an owner process to the owner count of the given construct()-created handle, and returns an opaq...">lend_object()</a> that returned <code>serialization</code>; to be invoked in the intended new owner process. </p>
<p >Returns null if no pool attached to <code>*this</code>.</p>
<p >Consider the only 2 ways a user may obtain a new <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a662a55c9ba6eb5c389ddf9780ee801cb" title="Outer handle to a SHM-stored object; really a regular-looking shared_ptr but with custom deleter that...">Handle</a> to a <code>T</code> from <code>*this</code>:</p><ul>
<li><a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#ab9f7ea056a55183d00dcbce573afcf36" title="Constructs an object of given type with given ctor args, having allocated space directly in attached ...">construct()</a>: This is allocation by the original/first owner of the <code>T</code>.</li>
<li><a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#ad2f2b767d7da42e7e57592cc029386e5" title="Completes the cross-process operation begun by lend_object() that returned serialization; to be invok...">borrow_object()</a>, after <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#acb300e64f92ab0aa5b70f8313c79a899" title="Adds an owner process to the owner count of the given construct()-created handle, and returns an opaq...">lend_object()</a> was called on a previous <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a662a55c9ba6eb5c389ddf9780ee801cb" title="Outer handle to a SHM-stored object; really a regular-looking shared_ptr but with custom deleter that...">Handle</a> in another process, acquired <em>there</em> however it was acquired:<ul>
<li>Acquired via <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#ab9f7ea056a55183d00dcbce573afcf36" title="Constructs an object of given type with given ctor args, having allocated space directly in attached ...">construct()</a>: I.e., the original/first owner lent to us. I.e., it's the original loan.</li>
<li>Acquired via another <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#ad2f2b767d7da42e7e57592cc029386e5" title="Completes the cross-process operation begun by lend_object() that returned serialization; to be invok...">borrow_object()</a>: I.e., it was itself first borrowed from another. I.e., it's a loan by a lender a/k/a <em>proxying</em>.</li>
</ul>
</li>
</ul>
<h3>Integration with <a class="el" href="classipc_1_1shm_1_1stl_1_1Stateless__allocator.html" title="Stateless allocator usable with STL-compliant containers to store (or merely read) them directly in S...">shm::stl::Stateless_allocator</a></h3>
<p >Crucially, the 2nd paragraph of similarly named section of <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#ab9f7ea056a55183d00dcbce573afcf36" title="Constructs an object of given type with given ctor args, having allocated space directly in attached ...">construct()</a> doc header &ndash; where it speaks of applying <code>Stateless_allocator</code> context around dtor call possibly invoked by returned handle's deleter &ndash; applies exactly equally here. Please read it.</p>
<dl class="tparams"><dt>Template Parameters</dt><dd>
  <table class="tparams">
    <tr><td class="paramname">T</td><td>See <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#acb300e64f92ab0aa5b70f8313c79a899" title="Adds an owner process to the owner count of the given construct()-created handle, and returns an opaq...">lend_object()</a>. </td></tr>
  </table>
  </dd>
</dl>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">serialization</td><td>Value, not <code>.empty()</code>, returned by <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#acb300e64f92ab0aa5b70f8313c79a899" title="Adds an owner process to the owner count of the given construct()-created handle, and returns an opaq...">lend_object()</a> and transmitted bit-for-bit to this process. </td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Non-null on success; <code>null</code> if ctor failed to attach a pool. </dd></dl>

</div>
</div>
<a id="ab9f7ea056a55183d00dcbce573afcf36" name="ab9f7ea056a55183d00dcbce573afcf36"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ab9f7ea056a55183d00dcbce573afcf36">&#9670;&nbsp;</a></span>construct()</h2>

<div class="memitem">
<div class="memproto">
<div class="memtemplate">
template&lt;typename T , typename... Ctor_args&gt; </div>
      <table class="memname">
        <tr>
          <td class="memname"><a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a662a55c9ba6eb5c389ddf9780ee801cb">Pool_arena::Handle</a>&lt; T &gt; ipc::shm::classic::Pool_arena::construct </td>
          <td>(</td>
          <td class="paramtype">Ctor_args &amp;&amp;...&#160;</td>
          <td class="paramname"><em>ctor_args</em></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Constructs an object of given type with given ctor args, having allocated space directly in attached SHM pool, and returns a ref-counted handle that (1) guarantees destruction and deallocation shall occur once no owners hold a reference; and (2) can be lent to other processes (and other processes still indefinitely), thus adding owners beyond this process, via <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#acb300e64f92ab0aa5b70f8313c79a899" title="Adds an owner process to the owner count of the given construct()-created handle, and returns an opaq...">lend_object()</a>/borrow_object(). </p>
<p >Returns null if no pool attached to <code>*this</code>. Throws exception if ran out of space.</p>
<p >Is better to use this than <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a9da3a100a0b7199644edbadacc9083c9" title="Allocates buffer of specified size, in bytes, in the accessed pool; returns locally-derefernceable ad...">allocate()</a> whenever possible; see class doc header notes on this.</p>
<p >Note that that there is no way to <code><a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#ab9f7ea056a55183d00dcbce573afcf36" title="Constructs an object of given type with given ctor args, having allocated space directly in attached ...">construct()</a></code> a native array. If that is your aim please use <code>T = std::array&lt;&gt;</code> or similar.</p>
<h3>Integration with <a class="el" href="classipc_1_1shm_1_1stl_1_1Stateless__allocator.html" title="Stateless allocator usable with STL-compliant containers to store (or merely read) them directly in S...">shm::stl::Stateless_allocator</a></h3>
<p >This method, bracketing the invocation of the <code>T</code> ctor, sets the thread-local <code><a class="el" href="classipc_1_1shm_1_1stl_1_1Arena__activator.html" title="RAII-style class operating a stack-like notion of a the given thread&#39;s currently active SHM-aware Are...">shm::stl::Arena_activator</a>&lt;<a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html" title="A SHM-classic interface around a single SHM pool with allocation-algorithm services by boost....">Pool_arena</a>&gt;</code> context to <code>this</code>. Therefore the caller need not do so. If <code>T</code> does not store an STL-compliant structure that uses <code>Stateless_allocator</code>, then this is harmless albeit a small perf hit. If <code>T</code> does do so, then it is a convenience.</p>
<p >Arguably more importantly: The returned <code>shared_ptr</code> is such that when garbage-collection of the created data structure does occur &ndash; which may occur in this process, but via <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#acb300e64f92ab0aa5b70f8313c79a899" title="Adds an owner process to the owner count of the given construct()-created handle, and returns an opaq...">lend_object()</a> and <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#ad2f2b767d7da42e7e57592cc029386e5" title="Completes the cross-process operation begun by lend_object() that returned serialization; to be invok...">borrow_object()</a> may well occur in another process &ndash; the <code>T::~T()</code> <em>dtor</em> call shall also be bracketed by the aforementioned context. Again: If <code>T</code> does not rely on <code>Stateless_allocator</code>, then it's harmless; but if it <em>does</em> then doing this is quite essential. That is because the user cannot, typically (or at least sufficiently easily), control the per-thread allocator context at the time of dtor call &ndash; simply because who knows who or what will be running when the cross-process ref-count reaches 0.</p>
<dl class="tparams"><dt>Template Parameters</dt><dd>
  <table class="tparams">
    <tr><td class="paramname">T</td><td>Object type. See class doc header for discussion on appropriate properties of <code>T</code>. Short version: PODs work; STL nested container+POD combos work, as long as a <a class="el" href="namespaceipc_1_1shm_1_1stl.html" title="ipc::shm sub-module providing integration between STL-compliant components (including containers) and...">shm::stl</a> allocator is used at all levels; manually-implemented non-STL-compliant data structures work if care is taken to use <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a9da3a100a0b7199644edbadacc9083c9" title="Allocates buffer of specified size, in bytes, in the accessed pool; returns locally-derefernceable ad...">allocate()</a> and <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a07fec7ff0ba494dca0f0a010270cc35f" title="SHM-storable fancy-pointer.">Pointer</a>. </td></tr>
    <tr><td class="paramname">Ctor_args</td><td><code>T</code> ctor arg types. </td></tr>
  </table>
  </dd>
</dl>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">ctor_args</td><td>0 or more args to <code>T</code> constructor. </td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Non-null on success; <code>null</code> if ctor failed to attach a pool. </dd></dl>

</div>
</div>
<a id="a394973b7cfb67b67113043810804337d" name="a394973b7cfb67b67113043810804337d"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a394973b7cfb67b67113043810804337d">&#9670;&nbsp;</a></span>deallocate()</h2>

<div class="memitem">
<div class="memproto">
<table class="mlabels">
  <tr>
  <td class="mlabels-left">
      <table class="memname">
        <tr>
          <td class="memname">bool ipc::shm::classic::Pool_arena::deallocate </td>
          <td>(</td>
          <td class="paramtype">void *&#160;</td>
          <td class="paramname"><em>buf_not_null</em></td><td>)</td>
          <td></td>
        </tr>
      </table>
  </td>
  <td class="mlabels-right">
<span class="mlabels"><span class="mlabel">noexcept</span></span>  </td>
  </tr>
</table>
</div><div class="memdoc">

<p>Undoes effects of local <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a9da3a100a0b7199644edbadacc9083c9" title="Allocates buffer of specified size, in bytes, in the accessed pool; returns locally-derefernceable ad...">allocate()</a> that returned <code>buf_not_null</code>; or another-process's <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a9da3a100a0b7199644edbadacc9083c9" title="Allocates buffer of specified size, in bytes, in the accessed pool; returns locally-derefernceable ad...">allocate()</a> that returned pointer whose locally-dereferenceable equivalent is <code>but_not_null</code>. </p>
<p >Returns <code>false</code> if and only if no pool attached to <code>*this</code>. Does not throw exception. Behavior is undefined if <code>buf_not_null</code> is not as described above; in particular if it is null.</p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">buf_not_null</td><td>See above. </td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd><code>true</code> on success; <code>false</code> if ctor failed to attach a pool. </dd></dl>

</div>
</div>
<a id="a9e720283945eefe3d941b185e95d2ce1" name="a9e720283945eefe3d941b185e95d2ce1"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a9e720283945eefe3d941b185e95d2ce1">&#9670;&nbsp;</a></span>for_each_persistent()</h2>

<div class="memitem">
<div class="memproto">
<div class="memtemplate">
template&lt;typename Handle_name_func &gt; </div>
<table class="mlabels">
  <tr>
  <td class="mlabels-left">
      <table class="memname">
        <tr>
          <td class="memname">void ipc::shm::classic::Pool_arena::for_each_persistent </td>
          <td>(</td>
          <td class="paramtype">const Handle_name_func &amp;&#160;</td>
          <td class="paramname"><em>handle_name_func</em></td><td>)</td>
          <td></td>
        </tr>
      </table>
  </td>
  <td class="mlabels-right">
<span class="mlabels"><span class="mlabel">static</span></span>  </td>
  </tr>
</table>
</div><div class="memdoc">

<p>Lists all named SHM pool objects currently persisting, invoking the given handler synchronously on each one. </p>
<p >Note that, in a sanely set-up OS install, all existing pools will be listed by this function; but permissions/ownership may forbid certain operations the user may typically want to invoke on a given listed name &ndash; for example <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#aff2327ce7339c1c732ddd4fcd4861ee4" title="Removes the named SHM pool object.">remove_persistent()</a>. This function does <em>not</em> filter-out any potentially inaccessible items.</p>
<dl class="section note"><dt>Note</dt><dd>The listed pools need not have been created via <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html" title="A SHM-classic interface around a single SHM pool with allocation-algorithm services by boost....">Pool_arena</a> objects; they will be all pools created by name ultimately via OS <code>shm_open()</code> or equivalent call. Therefore this is a utility that is not limited for use in the <a class="el" href="namespaceipc_1_1shm_1_1classic.html" title="ipc::shm sub-module with the SHM-classic SHM-provider. See ipc::shm doc header for introduction.">ipc::shm::classic</a> context.</dd></dl>
<dl class="tparams"><dt>Template Parameters</dt><dd>
  <table class="tparams">
    <tr><td class="paramname">Handle_name_func</td><td>Function object matching signature <code>void F(const Shared_name&amp;)</code>. </td></tr>
  </table>
  </dd>
</dl>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">handle_name_func</td><td><code>handle_name_func()</code> shall be invoked for each item. See <code>Handle_name_func</code>. </td></tr>
  </table>
  </dd>
</dl>

</div>
</div>
<a id="ad2d54cc87b56613bba32aabd2c52ef13" name="ad2d54cc87b56613bba32aabd2c52ef13"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ad2d54cc87b56613bba32aabd2c52ef13">&#9670;&nbsp;</a></span>is_handle_in_arena()</h2>

<div class="memitem">
<div class="memproto">
<div class="memtemplate">
template&lt;typename T &gt; </div>
      <table class="memname">
        <tr>
          <td class="memname">bool ipc::shm::classic::Pool_arena::is_handle_in_arena </td>
          <td>(</td>
          <td class="paramtype">const <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a662a55c9ba6eb5c389ddf9780ee801cb">Handle</a>&lt; T &gt; &amp;&#160;</td>
          <td class="paramname"><em>handle</em></td><td>)</td>
          <td> const</td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Returns <code>true</code> if and only if <code>handle</code> came from either <code>this-&gt;construct&lt;T&gt;()</code> or <code>this-&gt;borrow_object&lt;T&gt;()</code>. </p>
<p >Another way of saying that is: if and only if <code>handle</code> may be passed to <code>this-&gt;lend_object&lt;T&gt;()</code>. (The words "came from" mean "was returned by or is a copy/move of one that was," or equivalently "belongs to the `shared_ptr` group of one that was returned by.")</p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">handle</td><td>An object, or copy/move of an object, returned by <code>construct&lt;T&gt;()</code> or <code>borrow_object&lt;T&gt;()</code> of <em>a</em> <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html" title="A SHM-classic interface around a single SHM pool with allocation-algorithm services by boost....">Pool_arena</a> (not necessarily <code>*this</code>), while <code>*this</code> was already constructed. </td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>See above. </dd></dl>

</div>
</div>
<a id="acb300e64f92ab0aa5b70f8313c79a899" name="acb300e64f92ab0aa5b70f8313c79a899"></a>
<h2 class="memtitle"><span class="permalink"><a href="#acb300e64f92ab0aa5b70f8313c79a899">&#9670;&nbsp;</a></span>lend_object()</h2>

<div class="memitem">
<div class="memproto">
<div class="memtemplate">
template&lt;typename T &gt; </div>
      <table class="memname">
        <tr>
          <td class="memname"><a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a72867ce6e363dbc1ab1666768d8a7a09">Pool_arena::Blob</a> ipc::shm::classic::Pool_arena::lend_object </td>
          <td>(</td>
          <td class="paramtype">const <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a662a55c9ba6eb5c389ddf9780ee801cb">Handle</a>&lt; T &gt; &amp;&#160;</td>
          <td class="paramname"><em>handle</em></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Adds an owner process to the owner count of the given <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#ab9f7ea056a55183d00dcbce573afcf36" title="Constructs an object of given type with given ctor args, having allocated space directly in attached ...">construct()</a>-created handle, and returns an opaque blob, such that if one passes it to <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#ad2f2b767d7da42e7e57592cc029386e5" title="Completes the cross-process operation begun by lend_object() that returned serialization; to be invok...">borrow_object()</a> in the receiving process, that <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#ad2f2b767d7da42e7e57592cc029386e5" title="Completes the cross-process operation begun by lend_object() that returned serialization; to be invok...">borrow_object()</a> shall return an equivalent <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a662a55c9ba6eb5c389ddf9780ee801cb" title="Outer handle to a SHM-stored object; really a regular-looking shared_ptr but with custom deleter that...">Handle</a> in that process. </p>
<p >The returned <code>Blob</code> is guaranteed to have non-zero size that is small enough to be considered very cheap to copy; in particular internally as of this writing it is a <code>ptrdiff_t</code>. Returns <code>.empty()</code> object if no pool attached to <code>*this</code>.</p>
<p >It is the user's responsibility to transmit the returned blob, such as via a <a class="el" href="classipc_1_1transport_1_1Channel.html" title="Peer to a bundle of 1-2 full-duplex pipe(s), one for transmitting unstructured binary blobs; the othe...">transport::Channel</a> or any other copying IPC mechanism, to the owning process. Failing to do so will leak the object until <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#aff2327ce7339c1c732ddd4fcd4861ee4" title="Removes the named SHM pool object.">remove_persistent()</a>. That process dying without running <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a662a55c9ba6eb5c389ddf9780ee801cb" title="Outer handle to a SHM-stored object; really a regular-looking shared_ptr but with custom deleter that...">Handle</a> dtor(s) will similarly leak it.</p>
<dl class="tparams"><dt>Template Parameters</dt><dd>
  <table class="tparams">
    <tr><td class="paramname">T</td><td>See <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#ab9f7ea056a55183d00dcbce573afcf36" title="Constructs an object of given type with given ctor args, having allocated space directly in attached ...">construct()</a>. </td></tr>
  </table>
  </dd>
</dl>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">handle</td><td>Value returned by <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#ab9f7ea056a55183d00dcbce573afcf36" title="Constructs an object of given type with given ctor args, having allocated space directly in attached ...">construct()</a> (lending from original allocating process) or <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#ad2f2b767d7da42e7e57592cc029386e5" title="Completes the cross-process operation begun by lend_object() that returned serialization; to be invok...">borrow_object()</a> (proxying); or copied/moved therefrom. Note this is a mere <code>shared_ptr&lt;T&gt;</code> albeit with unspecified custom deleter logic attached. See <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a662a55c9ba6eb5c389ddf9780ee801cb" title="Outer handle to a SHM-stored object; really a regular-looking shared_ptr but with custom deleter that...">Handle</a> doc header. </td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>See above. <code>.empty()</code> if and only if ctor failed to attach a pool. </dd></dl>

</div>
</div>
<a id="aff2327ce7339c1c732ddd4fcd4861ee4" name="aff2327ce7339c1c732ddd4fcd4861ee4"></a>
<h2 class="memtitle"><span class="permalink"><a href="#aff2327ce7339c1c732ddd4fcd4861ee4">&#9670;&nbsp;</a></span>remove_persistent()</h2>

<div class="memitem">
<div class="memproto">
<table class="mlabels">
  <tr>
  <td class="mlabels-left">
      <table class="memname">
        <tr>
          <td class="memname">void ipc::shm::classic::Pool_arena::remove_persistent </td>
          <td>(</td>
          <td class="paramtype">flow::log::Logger *&#160;</td>
          <td class="paramname"><em>logger_ptr</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">const <a class="el" href="namespaceipc_1_1shm_1_1classic.html#ac0a52218467710995cc6c74538be6012">Shared_name</a> &amp;&#160;</td>
          <td class="paramname"><em>name</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype"><a class="el" href="namespaceipc.html#aa3192e586cc45d3e7c22463bf2760f89">Error_code</a> *&#160;</td>
          <td class="paramname"><em>err_code</em> = <code>0</code>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
  </td>
  <td class="mlabels-right">
<span class="mlabels"><span class="mlabel">static</span></span>  </td>
  </tr>
</table>
</div><div class="memdoc">

<p>Removes the named SHM pool object. </p>
<p >The name <code>name</code> is removed from the system immediately; and the function is non-blocking. However the underlying pool if any continues to exist until all handles (accessor objects <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html" title="A SHM-classic interface around a single SHM pool with allocation-algorithm services by boost....">Pool_arena</a> or other OS-created handles) to it are closed; their presence in this or other process is <em>not</em> an error. See also dtor doc header for related notes.</p>
<dl class="section note"><dt>Note</dt><dd>The specified pool need not have been created via a <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html" title="A SHM-classic interface around a single SHM pool with allocation-algorithm services by boost....">Pool_arena</a> object; it can be any pool created by name ultimately via OS <code>shm_open()</code> or equivalent call. Therefore this is a utility that is not limited for use in the <a class="el" href="namespaceipc_1_1shm_1_1classic.html" title="ipc::shm sub-module with the SHM-classic SHM-provider. See ipc::shm doc header for introduction.">ipc::shm::classic</a> context. </dd></dl>
<dl class="section see"><dt>See also</dt><dd><code>util::remove_each_persistent_*</code>() for a convenient way to remove more than one item. E.g., <code><a class="el" href="namespaceipc_1_1util.html#ad6be904bf1b0fe6659a11dec0fabbf6b" title="Utility that invokes remove_each_persistent_if() with the filter that returns true (yes,...">util::remove_each_persistent_with_name_prefix</a>&lt;<a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html" title="A SHM-classic interface around a single SHM pool with allocation-algorithm services by boost....">Pool_arena</a>&gt;()</code> combines <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#aff2327ce7339c1c732ddd4fcd4861ee4" title="Removes the named SHM pool object.">remove_persistent()</a> and <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html#a9e720283945eefe3d941b185e95d2ce1" title="Lists all named SHM pool objects currently persisting, invoking the given handler synchronously on ea...">for_each_persistent()</a> in a common-sense way to remove only those <code>name</code>s starting with a given prefix; or simply all of them.</dd></dl>
<p>Trying to remove a non-existent name <em>is</em> an error.</p>
<p >Logs INFO message.</p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">logger_ptr</td><td>Logger to use for subsequently logging. </td></tr>
    <tr><td class="paramname">name</td><td>Absolute name at which the persistent SHM pool lives. </td></tr>
    <tr><td class="paramname">err_code</td><td>See <code>flow::Error_code</code> docs for error reporting semantics. <a class="el" href="namespaceipc.html#aa3192e586cc45d3e7c22463bf2760f89" title="Short-hand for flow::Error_code which is very common.">Error_code</a> generated: various. Most likely it'll be a not-found error or permissions error. </td></tr>
  </table>
  </dd>
</dl>

</div>
</div>
<h2 class="groupheader">Friends And Related Function Documentation</h2>
<a id="a4abe6573298da49d0914dd068a086f2c" name="a4abe6573298da49d0914dd068a086f2c"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a4abe6573298da49d0914dd068a086f2c">&#9670;&nbsp;</a></span>operator&lt;&lt;()</h2>

<div class="memitem">
<div class="memproto">
<table class="mlabels">
  <tr>
  <td class="mlabels-left">
      <table class="memname">
        <tr>
          <td class="memname">std::ostream &amp; operator&lt;&lt; </td>
          <td>(</td>
          <td class="paramtype">std::ostream &amp;&#160;</td>
          <td class="paramname"><em>os</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">const <a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html">Pool_arena</a> &amp;&#160;</td>
          <td class="paramname"><em>val</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
  </td>
  <td class="mlabels-right">
<span class="mlabels"><span class="mlabel">related</span></span>  </td>
  </tr>
</table>
</div><div class="memdoc">

<p>Prints string representation of the given <code><a class="el" href="classipc_1_1shm_1_1classic_1_1Pool__arena.html" title="A SHM-classic interface around a single SHM pool with allocation-algorithm services by boost....">Pool_arena</a></code> to the given <code>ostream</code>. </p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">os</td><td>Stream to which to write. </td></tr>
    <tr><td class="paramname">val</td><td>Object to serialize. </td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd><code>os</code>. </dd></dl>

</div>
</div>
<hr/>The documentation for this class was generated from the following files:<ul>
<li>shm/classic/<a class="el" href="pool__arena_8hpp.html">pool_arena.hpp</a></li>
<li>shm/classic/<a class="el" href="shm_2classic_2classic__fwd_8hpp.html">classic_fwd.hpp</a></li>
<li>shm/classic/<a class="el" href="pool__arena_8cpp.html">pool_arena.cpp</a></li>
</ul>
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Thu May 2 2024 23:56:35 for Flow-IPC by&#160;<a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.4
</small></address>
</body>
</html>
